\name{dataSynthesis}
\alias{dataSynthesis}

\title{Build a Standard Plotting Data Set for a Given NONR Run}
\description{

  dataSynthesis() scavenges columns from the TAB file, the par.TAB file, and the 
  underlying dataset, returning just observation records (EVID==0) that are  not
  commented.  The second two files are limited to the first record per ID. Columns 
  to scavenge are supplied by grp, cont.cov, cat.cov, par.list, and eta.list.
  All TAB file columns are returned, plus first instance of 'scavenge' columns from 
  either the parent data set or the par file (in that order) unless already present.
 
}
\usage{
  dataSynthesis(
	run, 
	ProjectDir=getwd(), 
	dvname = 'DV',
	logtrans = FALSE,
	grp = NULL, 
	grpnames = NULL,
	cont.cov = NULL,
	cat.cov = NULL,
	par.list = NULL,
	eta.list = NULL,
	missing = -99,
	tabfile = filename(outdir, run, '.TAB'),
	ctlfile = filename(rundir,run,'.ctl'),
	outfile = filename(rundir,run,'.lst'),
	datfile = getdname(ctlfile),
	parfile = filename(outdir, run, 'par.TAB'),
	rundir  = filename(ProjectDir, run),
	outdir  = ProjectDir,
	...
)
}

\arguments{
  \item{run}{A control stream name, typically integer.}
  \item{ProjectDir}{The directory containing the NONMEM control (*.ctl) streams.}
  \item{dvname}{{Name of the dependent variable to use as a label for the diagnostic plots. Default: DV.}}
  \item{logtrans}{Whether to transform the NONMEM output variables DV,
  PRED, and IPRED. Default: FALSE.}
  \item{grp}{Item in
  NONMEM datafile or output table file that can be used to condition
  plots generated by PLOTR.  Default value is NULL. Example:
  \code{grp=c("SEX")}.  Can be more than one, e.g,. grp=c("SEX","TRT").}
  \item{grpnames}{Optional vector of names for
  \code{grp} item. Vector length must equal number of conditions in
  \code{grp} and must have an order corresponding to an increasing sort
  of \code{grp}.  Default value is NULL. Example:
  \code{grpnames=c("Male","Female")}}
  \item{cont.cov}{Vector of
  continuous covariate names. Names must match those used as column
  headers in \code{DataFile}.  Values are retrieved from \code{DataFile}
  so they do not need to be part of the NONMEM \$TABLE step. Default
  value is NULL.  Example: \code{cont.cov=c("AGE","WT","CLCR")}}
  \item{cat.cov}{Vector of categorical covariate names. Names must match
  those used as column headers in \code{DataFile}.  Values are retrieved
  from \code{DataFile} so they do not need to be part of the NONMEM
  \$TABLE step. Default value is NULL.  Example:
  \code{cat.cov=c("SEX","FOOD")}} 
  \item{par.list}{Vector of NONMEM model
  parameter names.  Values are retrieved from *par.TAB created in
  NONMEM. Default value is NULL.  This can be a superset of parameters
  but only those present in NONMEM output table will be used. Example:
  \code{par.list=c("CL","V","V2","Q")}} 
  \item{eta.list}{Vector of NONMEM
  model random effect names. Values are retrieved from *par.TAB created
  in NONMEM. Default value is NULL This can be a superset of random
  parameters but only those present in NONMEM output table will be used.
  Example: \code{eta.list=c("ETA1","ETA2","ETA3","ETA4")}}
  \item{missing}{Numeric item that defines value used to represent
  missing items in the NONMEM data file. Default value is "-99".}
  \item{tabfile}{Path and filename for the NONMEM output table (*.TAB).}
  \item{ctlfile}{Path and filename for the NONMEM control stream (*.ctl).}
  \item{outfile}{Path and filename for the NONMEM output file (*.lst).}
  \item{datfile}{Path and filename for the source dataset, as in DATA record in *.ctl.}
  \item{parfile}{Path and filename for the NONMEM parameter file (*par.TAB).}
  \item{rundir}{Path for the NONMEM run directory (ProjectDir/*).}
  \item{outdir}{Path for the NONMEM output directory (ProjectDir). Not related
  to \code{outfile}.  Controls defaults for where to look for \code{tabfile} and
  \code{outfile}, as well as where to put \code{file}.}
  \item{\dots}{}
}
\value{data.frame}
\references{mifuns.googlecode.com}
\author{Tim Bergsma}
\seealso{ \code{\link{diagnosticPlots}},\code{\link{dataFormat}}}
\keyword{manip}

